Obtains the location of a mouse-down event in a control.

ControlPartCode FindControl (
    Point testPoint, 
    WindowRef theWindow, 
    ControlRef *theControl
);

Parameter descriptions

testPoint

A point, specified in coordinates local to the window, where the mouse-down event occurred. Before calling FindControl, use the GlobalToLocal function to convert the point stored in the where field of the event structure (which describes the location of the mouse-down event) to coordinates local to the window.

theWindow

A pointer to the window in which the mouse-down event occurred. Pass the window pointer returned by the FindWindow function.

theControl

A pointer to a control handle. On output, FindControl returns a handle to the control in which the mouse-down event occurred or NULL if the point was not over a control.

function result

The control part code of the control in which the mouse-down event occured; see “Meta Control Part Code Constants”, “Control Part Code Constants”, and “Control State Part Code Constants”.

DISCUSSION

The FindControl function is not recommended when the Appearance Manager is available. When the Appearance Manager is available, you should call FindControlUnderMouse to determine the location of a mouse-down event in a control. FindControlUnderMouse will return a handle to the control even if no part was hit and can determine whether a mouse-down event has occurred even if the control is deactivated, while FindControl does not.

If the Appearance Manager is not available, then, when a mouse-down event occurs, your application can call FindControl after using the Window Manager function FindWindow to ascertain that a mouse-down event has occurred in the content region of a window containing controls.

When the user presses the mouse button while the cursor is in a visible, active control, FindControl returns as its function result a part code identifying the control’s part; the function also returns a handle to the control in the parameter theControl.

If the mouse-down event occurs in an invisible or inactive control, or if it occurs outside a control, FindControl sets the value referenced through theControl to NULL and returns 0 as its function result.

The FindControl function also returns NULL in the value referenced through the parameter theControl and 0 as its function result if the window is invisible or if it doesn’t contain the given point. (However, FindWindow won’t return a window pointer to an invisible window or to one that doesn’t contain the point where the mouse-down event occurred. As long as you call FindWindow before FindControl, this situation won’t arise.)

After using FindControl to determine that a mouse-down event has occurred in a control, you typically call the function TrackControl to follow and respond to the cursor movements in that control, and then to determine in which part of the control the mouse-up event occurs.

The pop-up control definition function does not define part codes for pop-up menus. Instead, your application should store the handles for your pop-up menus when you create them. Your application should then test the handles you store against the handles returned by FindControl before responding to users’ choices in pop-up menus.

The Dialog Manager automatically calls FindControl and TrackControl for mouse-down events inside controls of alert boxes and dialog boxes.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.

© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)